\defmodule {Simulator}

Represents the executive of a discrete-event simulator.
This class maintains a simulation
clock, an event list, and starts executing the events
%and processes
in the appropriate order.
Its methods permit one to start, stop, and (re)initialize the simulation,
and read the simulation clock.

Usually, a simulation program uses a single simulation clock which is
represented by an instance of this class.
For more convenience and compatibility, this class therefore provides
a mechanism to construct and return a default simulator
which is used when an event is constructed without an explicit reference to a
simulator, and when the simulator is accessed through
the \class{Sim} class.

Note that this class is NOT thread-safe.  Consequently, if a simulation program
uses multiple threads, it should acquire a lock on a simulator (using a
\texttt{synchronized} block) before accessing its state.
Note however, that one can launch many simulations in parallel with as many
threads, as long as \emph{each thread has its own} \texttt{Simulator}.

%At last, this class provides tools to manage a default simulator variable thanks to its static methods.

\bigskip\hrule

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{code}
\begin{hide}
/*
 * Class:        Simulator
 * Description:  Represents the executive of a discrete-event simulator
 * Environment:  Java
 * Software:     SSJ
 * Copyright (C) 2001  Pierre L'Ecuyer and Universite de Montreal
 * Organization: DIRO, Universite de Montreal
 * @author
 * @since

 * SSJ is free software: you can redistribute it and/or modify it under
 * the terms of the GNU General Public License (GPL) as published by the
 * Free Software Foundation, either version 3 of the License, or
 * any later version.

 * SSJ is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.

 * A copy of the GNU General Public License is available at
   <a href="http://www.gnu.org/licenses">GPL licence site</a>.
 */
\end{hide}
package umontreal.iro.lecuyer.simevents;\begin{hide}

import umontreal.iro.lecuyer.simevents.eventlist.EventList;
import umontreal.iro.lecuyer.simevents.eventlist.SplayTree;
import umontreal.iro.lecuyer.simprocs.*;\end{hide}
   import java.util.ListIterator;

public class Simulator \begin{hide} {

   protected double currentTime = 0.0;
      // The current simulation time (clock).

   protected EventList eventList;
      // The list of future events.
      // Can be changed by the method \texttt{init}.

   protected boolean stopped = true;
      // Becomes true when the simulation has ended
      // (stopped has been called or the event list is empty).

   protected boolean simulating = false;

   protected ContinuousState continuousState = null; \end{hide}

   public static Simulator defaultSimulator\begin{hide} = null;\end{hide}
\end{code}
   \begin{tabb} Represents the default simulator being used by the
     class \class{Sim}, and the no-argument constructor of \class{Event}.
     This simulator is usually obtained with the
     \method{getDefaultSimulator}{} method, which initializes it if needed.
     But it might also be initialized
     differently, e.g., if process-driven simulation is required.
   \end{tabb}
\subsubsection*{Constructors}
\begin{code}

   public Simulator()\begin{hide} {
     eventList  = new SplayTree();
   }\end{hide}
\end{code}
\begin{tabb}  Constructs a new simulator using a splay tree for the
  event list.
\end{tabb}
\begin{code}

   public Simulator (EventList eventList)\begin{hide} {
     if (eventList == null)
        throw new NullPointerException();
     this.eventList = eventList;
   }\end{hide}
\end{code}
\begin{tabb}  Constructs a new simulator using \texttt{eventList} for
  the event list.
\end{tabb}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection* {Methods}

\begin{code}

   public double time() \begin{hide}
   {
      return currentTime;
   }\end{hide}
\end{code}
   \begin{tabb} Returns the current value of the simulation clock. \end{tabb}
\begin{htmlonly}
   \return{the current simulation time}
\end{htmlonly}
\begin{code}

   public void init() \begin{hide} {
     // This has to be done another way in order to separate events and processes.
//      SimProcess.killAll();
      currentTime = 0.0;   eventList.clear();   stopped = false;  simulating = false;
   }\end{hide}
\end{code}
  \begin{tabb} Reinitializes the simulation executive by clearing up the event
   list, and resetting the simulation clock to zero.
  \end{tabb}
\begin{code}

   public void init (EventList evlist) \begin{hide} {
      if (evlist == null)
         throw new NullPointerException();
      eventList = evlist;
      ListIterator iter = eventList.listIterator();
      while(iter.hasNext())
         ((Event)iter.next()).setSimulator(this);
      init();
   }\end{hide}
\end{code}
  \begin{tabb} Same as \method{init}{}, but also chooses \texttt{evlist} as the
    event list to be used.
    For example, \texttt{init (new DoublyLinked())} initializes the simulation
    with a doubly linked linear structure for the event list. To initialize the
    current \texttt{Simulator} with a not empty eventList is also possible, but
    the events scheduled in the eventList will be linked with the current simulator only.
  \end{tabb}
\begin{htmlonly}
   \param{evlist}{selected event list implementation}
\end{htmlonly}
\begin{code}

   public EventList getEventList()\begin{hide} {
      return eventList;
   }\end{hide}
\end{code}
\begin{tabb}  Gets the currently used event list.
\end{tabb}
\begin{htmlonly}
   \return{the currently used event list}
\end{htmlonly}
\begin{code}

   public boolean isSimulating()\begin{hide} {
       return simulating;
   }\end{hide}
\end{code}
\begin{tabb}  Determines if this simulator is currently running, i.e.,
  executing scheduled events.
\end{tabb}
\begin{code}

   public boolean isStopped()\begin{hide} {
       return stopped;
   }\end{hide}
\end{code}
\begin{tabb}  Determines if this simulator was stopped by
  an event.  The simulator may still be processing the event which
  has called the \method{stop}{} method; in this case,
  \method{isSimulating}{} returns \texttt{true}.
\end{tabb}
\begin{code}

   protected Event removeFirstEvent()\begin{hide} {
       if (stopped)
          return null;
       Event ev = eventList.removeFirst();
       if (ev == null)
          return null;
       currentTime = ev.eventTime;
       ev.eventTime = -10.0;
       return ev;
   }\end{hide}
\end{code}
\begin{tabb}  Removes the first event from the event list and sets the simulation
  clock to its event time.
\end{tabb}
\begin{htmlonly}
   \return{the first planned event, or \texttt{null} if there is no such event}
\end{htmlonly}
\begin{code}

   public void start () \begin{hide} {
      if (eventList.isEmpty())
        throw new IllegalStateException ("start() called with an empty event list");
      stopped = false;
      simulating = true;
      Event ev;
      try {
         while ((ev = removeFirstEvent()) != null && !stopped) {
   //      while (!stopped && (ev = eventList.removeFirst()) != null) {
   //          currentTime = ev.eventTime;
   //          ev.eventTime = -10.0;
             ev.actions();
             // if ev is a thread object associated to a process,
             // the control will be transfered to this thread and the
             // executive will be passivated in the actions() method.
         }
      }
      finally {
         stopped = true; simulating = false;
      }
   }\end{hide}
\end{code}
  \begin{tabb}  Starts the simulation executive.
   There must be at least one \texttt{Event} in the
   event list when this method is called.
  \end{tabb}
\begin{code}

   public void stop() \begin{hide}
   {
      stopped = true;
   }\end{hide}
\end{code}
  \begin{tabb} Tells the simulation executive to stop as soon as it takes control,
   and to return control to the program that called \method{start}{}.
   This program will then continue executing from the instructions right after
   its call to \method{start}. If an \class{Event} is currently executing (and
   this event has just called \method{stop}{}), the executive will take
   control when the event terminates its execution.
%   If a \texttt{SimProcess} is currently executing, the executive will take
%   control when the process terminates or suspends itself by invoking
%   one of its methods such as \texttt{delay}, \texttt{suspend},
%   \texttt{request}, etc.
  \end{tabb}
\begin{code}

   public ContinuousState continuousState() \begin{hide}
   {
      if (continuousState == null)
         continuousState = new ContinuousState(this);
      return continuousState;
   }\end{hide}
\end{code}
  \begin{tabb} Returns the current state of continuous variables being
    integrated during the simulation.
    This state is used by the \class{Continuous} class when performing
    simulation of continuous variables; it defaults to an empty state,
    which is initialized only when this method is called.
  \end{tabb}
  \begin{htmlonly}
   \return{continuousState field}
  \end{htmlonly}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\subsubsection* {Static methods}

\begin{code}

   public static Simulator getDefaultSimulator() \begin{hide} {
      if (defaultSimulator == null)
            defaultSimulator = new Simulator();
      return defaultSimulator;
   } \end{hide}
\end{code}
\begin{tabb} Returns the default simulator instance used by
  the deprecated class \class{Sim}.
  If this simulator does not exist yet, it is constructed using the
  no-argument constructor of this class.
  One can specify a different default simulator by setting
  the \texttt{defaultSimulator} field directly.
\end{tabb}
\begin{code}\begin{hide}
}\end{hide}
\end{code}
